Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 5 - Menu Manager Reference / Menu Manager Functions

Defining Your Own Contextual Menu Plug-In /

ExamineContext

NEW WITH CONTEXTUAL MENUS

Examines the context chosen by the user and determines possible menu commands appropriate to the context. If you write a contextual menu plug-in, it must contain an ExamineContext method with the following form:

OSStatus ExamineContext (AEDesc* inContextDescriptor, 
                     SInt32 inTimeOutInTicks, 
                     AEDescList* ioCommandPairs,
                     Boolean* outNeedMoreTime);

inContextDescriptor

The context chosen by the user. The Menu Manager passes this in the form of a pointer to an Apple Event descriptor. See Inside Macintosh: Interapplication Communication for information about the form of this descriptor. If there is no selection to examine, the pointer is NULL.

inTimeOutInTicks

The amount of time the plug-in is allowed to examine the context and create menu items.

ioCommandPairs

A pointer to an Apple Event descriptor list containing the commands allowed for this context.

outNeedMoreTime

Not currently used.

method result

A result code. See "Result Codes" for a list of possible values. If this value is not noErr then the Menu Manager does not use the plug-in in this case. However, it will call ExamineContext again the next time a contextual menu is invoked.

DISCUSSION

When a contextual menu is invoked, each module in the registry has its ExamineContext method called so it can inspect the context and add menu items as appropriate. After examining the context, the plug-in should then fill the AEDescList array with every command that it wants to add to the menu. This AEDescList will be created and disposed of for the plug-in; it will be empty when the plug-in receives it.

Each menu command that the plug-in can perform on the selection is described in an AERecord with two keyword-specified descriptor records. The structure of the AERecord is shown in Figure 5-5.

Figure 5-5 A menu command list in the AEDescList array

The first descriptor (keyAEName) is of typeIntlText and contains the text of the menu item to be added to the menu. The second descriptor (keyContextualMenuCommandID) is of type typeLongInteger and must contain a value specific to the plug-in that uniquely identifies this menu item.

If a plug-in wants to display a submenu for a particular menu item, it must use a variation of the AERecord used to describe a normal menu item. Figure 5-6 shows this variation.

Figure 5-6 A menu record showing submenus

The first descriptor (keyAEName) is the same, but the second descriptor uses a different keyword (keyContextualMenuSubmenu) and is of type typeAEList. It must contain an AEDescList with an AERecord for every command to be added to the submenu. Submenu items can themselves have submenus by recursively using this technique. The depth of the submenus is limited only by the constraints of the Menu Manager.